<title>ReaLua Misc and Util</title>

<p style="text-align: center; font-size: small">
<a href="index.html">Return to Index</a></p>

<h1 style="text-align: center;">ReaLua Miscellany and Utilities</h1>

<h2>Contents</h2>

<ol>
	<li>
		<a href="#misc">Miscellaneous Functions</a>
		<ol>
			<li><a href="#print">print</a></li>
			<li><a href="#oldprint">oldprint</a></li>
			<li><a href="#input">input</a></li>
			<li><a href="#exit">exit</a></li>
			<li><a href="#window">window</a></li>
			<li><a href="#cls">cls</a></li>
			<li><a href="#dump">dump</a></li>
		</ol>
	</li>

	<li>
		<a href="#util">Utility Functions and Tables</a>
		<ol>
		<li><a href="#keystack">keystack</a></li>
		<li><a href="#addmenu">addMenuCommand</a></li>
		<li><a href="#removemenu">removeMenuCommand</a></li>
		<li><a href="#hooks">hooks</a></li>
		<li><a href="#realua">realua</a></li>
		<li><a href="#sleep">sleep</a></li>
		<li><a href="#redraw">Redraw</a></li>
		<li><a href="#getmt">getmetatable</a></li>
		</ol>
	</li>
</ol>

<a name="misc"><h2>Miscellaneous Functions</h2></a>

<p>ReaLua puts the following few functions in the
global space, on the rationalization that the new
<code>print(<i>...</i>)</code> function is there,
so the other functions that deal with the
<a href="window.html">ReaLua Window</a>
go into the global space.
</p>

<dl>
	<dt><code><b>
		<a name="print">print</a>
	</b></code></dt>
	<dd>takes
		<code><i>...</i></code>
	</dd>
	<dd>returns
		<code>void <i></i></code>
	</dd>
</dl>

<p><code>print(<i>...</i>)</code> now sends its
output to the <a href="window.html">ReaLua Window</a>.
The old <code>stdio</code>-based
<code>print(<i>...</i>)</code> is stashed in the
<code>oldprint(<i>...</i>)</code> variable.
</p>

<dl>
	<dt><code><b>
		<a name="oldprint">oldprint</a>
	</b></code></dt>
	<dd>takes
		<code><i>...</i></code>
	</dd>
	<dd>returns
		<code>void <i></i></code>
	</dd>
</dl>

<p><code>oldprint(<i>...</i>)</code> is the old
<code>stdio</code>-based <code>print(<i>...</i>)</code>
function that will hang if you print too much!
</p>

<dl>
	<dt><code><b>
		<a name="input">input</a>
	</b></code></dt>
	<dl>
		<dt>takes</dt>
		<dd><code>string <i>prompt</i></code></dd>
		<dd>optional <code>string <i>default</i></code></dd>
	</dl>
	<dd>returns
		<code>string <i>response</i></code>
	</dd>
</dl>

<p>
<code>input(string <i>prompt</i>, optional string <i>default</i>)</code>
displays a dialog box with the given <code><i>prompt</i></code>
string, and optionally a <code><i>default</i></code> response
string.  It returns the user's response as a string.
</p>


<dl>
	<dt><code><b>
		<a name="exit">exit</a>
	</b></code></dt>
	<dd>takes
		<code>void<i></i></code>
	</dd>
	<dd>returns
		<code>void<i></i></code>
	</dd>
</dl>

<p><code>exit()</code> closes the
<a href="window.html">ReaLua Window</a>.  Use this
as the last line of a script to return the user to
Reaper.  Use as the first line of a script,
along with <code>reaper.Redraw()</code>,
to possess the Reaper muwhwaahahahaha!</p>

<blockquote><pre>
<code>exit()
reaper.Redraw()
reaper.CSurf_OnPlay()
reaper.sleep(3500)
reaper.CSurf_OnPlay()
</code>
</pre></blockquote>

<dl>
	<dt><code><b>
		<a name="window">window</a>
	</b></code></dt>
	<dd>takes
		<code>void<i></i></code>
	</dd>
	<dd>returns
		<code>void<i></i></code>
	</dd>
</dl>
<p><code>window()</code> opens the
<a href="window.html">ReaLua Window</a>.  Use this
as the first line of a script so subsequent
<code>print(<i>...</i>)</code>s are displayed.

<blockquote><pre>
<code>function ShowProjectMarkers()
  window()
  PrintProjectMarkers()
end
</code></pre></blockquote>


<dl>
	<dt><code><b>
		<a name="cls">cls</a>
	</b></code></dt>
	<dd>takes
		<code>void<i></i></code>
	</dd>
	<dd>returns
		<code>void<i></i></code>
	</dd>
</dl>

<p><code>cls()</code> clears the output area of the
<a href="window.html">ReaLua Window</a>.

<dl>
	<dt><code><b>
		<a name="dump">dump</a>
	</b></code></dt>
	<dl>
		<dt>takes</dt>
		<dd>optional <code>string <i>fileName</i></code></dd>
		<dd>optional <code>boolean <i>append</i></code></dd>
	</dl>
	<dd>returns
		<code>int <i>bytesWritten</i></code>
	</dd>
</dl>

<p>
<code>dump(</code>optional
<code>string <i>fileName</i>,</code>
optional <code>boolean <i>append</i>)</code> dumps
the contents of the <a href="window.html">ReaLua Window</a>'s
Output Area to a file.
</p>
<p>
Call <code>dump()</code> with no arguments to dump
to a file named "dump.txt" in the current
directory.  Call <code>dump()</code> with one
argument to control the file name (and directory).
If <code><i>append</i></code> is <code>true</code>,
the contents are appended to the named file.
</p>

<a name="util"><h2>Utilities</h2></a>

<p>The following utility functions and tables are in the
<a href="reaper.functions.html"><code>reaper</code></a> main table:
</p>

<dl>
	<dt><code><b>
		<a name="keystack">keystack</a>
	</b></code></dt>
	<dd>takes <code>... <i>keys</i></code></dd>
	<dd>returns <code>int <i>evtCount</i></code></dd>
</dl>

<p><code>reaper.keystack(<i>...</i>)</code> sends the
<code>VK_BLAH</code>s to the Reaper window, as
matched key-down and key-up events.  It returns
the number of events inserted into the event queue.
It can be used as an alternative to the
<code>reaper.Main_OnCommand(int <i>code</i>, int <i>arg</i>)</code>
function, for things that have key commands.
</p>

<dl>
	<dt><code><b>
		<a name="addmenu">addMenuCommand</a>
	</b></code></dt>
	<dl>
		<dt>takes</dt>
		<dd><code>string <i>commandText</i></code></dd>
		<dd><code>string <i>itemText</i></code></dd>
		<dd>optional <code>number <i>pos</i></code></dd>
	</dl>
	<dl>
		<dt>returns</dt>
		<dd><code>number <i>commandID</i></code>,</dd>
		<dd><code>number <i>pos</i></code></dd>
	</dl>
</dl>

<p>
<code>reaper.addMenuCommand(string <i>commandText</i>, string <i>itemText</i>, optional number <i>pos</i>)</code>
makes a menu item in the ReaLua Menu of Reaper's menu bar.
The Lua command to be executed (by <code>luaL_dostring()</code>)
is given by the <code><i>commandText</i></code> parameter.  The
<code><i>itemText</i></code> is the text displayed in the ReaLua Menu,
and it can have an <code>&amp;</code> (ampersand) keyboard accelerator.
Optionally, a position can be specified with <code><i>pos</i></code>.
If no <code><i>pos</i></code> is given, the item is appended.
<code>addMenuCommand</code> returns the Windows command ID and the position
at which the item was inserted.
</p>

<p>To add all of the members of the <i>pan</i> table to the ReaLua Menu,
<pre><code>for k in pairs(pan) do
    reaper.addMenuCommand("pan." .. k .. "()", "Pan " .. k)
end
</code>
</pre>
</p>


<img src="menu.png" alt="menu"><br>
<span style="border:1px solid black">Pans in Menu</span></img>


<dl>
	<dt><code><b>
		<a name="removemenu">removeMenuCommand</a>
	</b></code></dt>
	<dl>
		<dt>takes</dt>
		<dd><code>number <i>commandID</i></code></dd>
		<dd>or</dd>
		<dd><code>string <i>itemText</i></code></dd>
	</dl>
	<dd>returns <code>void<i></i></code></dd>
</dl>

<p>
<code>reaper.removeMenuCommand()</code>
removes the specified menu item from the ReaLua Menu, by either
the <code><i>commandID</i></code> returned from
<code>addMenuCommand()</code>
or the <code><i>itemText</i></code> passed to
<code>addMenuCommand()</code>.
</p>

<dl>
	<dt>the <code><b>
		<a name="hooks">hooks</a>
	</b></code> table</dt>
	<dl>
		<dt>key-value pairs</dt>
		<dd>key <code>number <i>commandID</i></code></dd>
		<dd>value <code>string <i>commandText</i></code></dd>
	</dl>
</dl>
<p>
<code>reaper.hooks</code> is a list of the hooked-up commands,
useful if you forgot the <code><i>commandID</i></code> return value.
[Not exactly the best name for this table, but not the worst either.]
</p>

<dl>
	<dt>the <code><b>
		<a name="realua">realua</a>
	</b></code> table</dt>
</dl>
<p>
<code>reaper.realua</code> is a table containing information about
ReaLua.</p>


<dl>
	<dt><code><b>
		<a name="sleep">sleep</a>
	</b></code></dt>
	<dd>takes optional <code>int <i>milliseconds</i>=0</code></dd>
	<dd>returns <code>void<i></i></code></dd>
</dl>
<p><code>sleep()</code> simply calls the Win32
<code>Sleep(DWORD <i>ms</i>)</code> function.  Useful
to give things time to happen.
</p>

<dl>
	<dt><code><b>
		<a name="redraw">Redraw</a>
	</b></code></dt>
	<dd>takes
		<code>void<i></i></code>
	</dd>
	<dd>returns
		<code>void<i></i></code>
	</dd>
</dl>

<p><code>reaper.Redraw()</code> simply calls the Win32
<code>Redraw(<i></i>)</code> function with the
Reaper window as its target.  Useful to show what's
going on.
</p>

<dl>
  <dt>
    <code><b>
		<a name="getmt">getmetatable</a>
	</b></code>
	<dd>takes
		<code>string <i>name</i></code>
	</dd>
	<dd>returns
		<code>{metatable}</code>
	</dd>
  </dt>
</dl>

<p>
<code>reaper.getmetatable(<i>name</i>)</code> gets the Reaper Type
metatable by name, the one which holds its
<code>_tostring</code>
(and maybe more):
    </p>


<p style="text-align: center; font-size: small">
<a href="index.html">Return to Index</a></p>
